What is clsx?
The clsx package is a tiny utility for constructing className strings conditionally. It is also a faster & smaller drop-in replacement for the 'classnames' library.
What are clsx's main functionalities?
Conditional class string construction
This feature allows you to construct a class string with conditional classes. If the condition is true, the class is included; otherwise, it is excluded. In the code sample, 'baz' will be included in the output string, while 'qux-quux' will not, resulting in 'foo bar baz'.
clsx('foo', 'bar', { 'baz': true, 'qux-quux': false })
Combining class strings
clsx can combine multiple class strings and arrays of class strings, ignoring falsy values. In the code sample, the output would be 'foo bar baz qux'.
clsx('foo', null, ['bar', 'baz'], { 'qux': true })
Handling arrays and nested arrays
clsx can handle arrays and nested arrays of class names with conditional logic. In the code sample, the output would be 'foo bar baz' as the nested array and object are properly evaluated.
clsx(['foo', ['bar', { 'baz': true }]])
Other packages similar to clsx
classnames
The 'classnames' package is the original utility that clsx was designed to replace. It offers similar functionality for conditionally joining classNames together. clsx claims to be a faster and smaller alternative to 'classnames'.
emotion
The 'emotion' package is a performant and flexible CSS-in-JS library. While it is more feature-rich, offering styled components and dynamic styling, it also includes the 'cx' function which is similar to clsx for combining class names conditionally.
clsx
![codecov](https://badgen.net/codecov/c/github/lukeed/clsx)
A tiny (228B) utility for constructing className
strings conditionally.
Also serves as a faster & smaller drop-in replacement for the classnames
module.
This module is available in three formats:
- ES Module:
dist/clsx.m.js
- CommonJS:
dist/clsx.js
- UMD:
dist/clsx.min.js
Install
$ npm install --save clsx
Usage
import clsx from 'clsx';
import { clsx } from 'clsx';
clsx('foo', true && 'bar', 'baz');
clsx({ foo:true, bar:false, baz:isTrue() });
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
clsx(['foo', 0, false, 'bar']);
clsx(['foo'], ['', 0, false, 'bar'], [['baz', [['hello'], 'there']]]);
clsx('foo', [1 && 'bar', { baz:false, bat:null }, ['hello', ['world']]], 'cya');
API
clsx(...input)
Returns: String
input
Type: Mixed
The clsx
function can take any number of arguments, each of which can be an Object, Array, Boolean, or String.
Important: Any falsey values are discarded!
Standalone Boolean values are discarded as well.
clsx(true, false, '', null, undefined, 0, NaN);
Benchmarks
For snapshots of cross-browser results, check out the bench
directory~!
Support
All versions of Node.js are supported.
All browsers that support Array.isArray
are supported (IE9+).
Note: For IE8 support and older, please install clsx@1.0.x
and beware of #17.
Related
- obj-str - A smaller (96B) and similiar utility that only works with Objects.
License
MIT © Luke Edwards